Open API
REST APIの仕様を記述したformat
Swaggerの後継
Swaggerは現在これらの開発ツールを表す言葉として残ったOpen API#63dc92c11280f000002027e5
この規格で記述されたREST APIから自動で各言語のclient/server libraryを生成するappがある
/icons/github.iconOpenAPITools/openapi-generator
online generator
解説
Swagger Editorからも出力できる
Open API Specification
旧名：Swagger Spec
Open APIの規格書と、Open APIの規格に準じて書いたdocumentの両方を指す？
記法
言語
JSONまたはYAML
ファイル名
openapi.jsonかopenapi.yamlが推奨されるhttps://swagger.io/specification/#document-structure
以前はswagger.jsonも使われていた？
OpenAPI (Swagger) 超入門 - Qiita
pathの解説
Paths Object | OpenAPI Specification - Version 3.0.3 | Swagger
https://swagger.io/docs/specification/about/
公式だとここがわかりやすい
JSON schemaはhttps://github.com/OAI/OpenAPI-Specification で配布されている
reponseの型定義はJSON schemaの記法で書く
Open API Specificationを書く
online Editor
Swagger Editor
vscode
yamlの拡張機能でJSON schemaを読ませれば、補完とvalidationが効く
JSON schemaはyaml拡張機能のshema選択promptから選べる
JSONでも書ける
VScodeのJSON言語機能が$dynamicRefをサポートしていないため、現状だと警告が出る
https://github.com/microsoft/vscode/issues/155379
https://stackoverflow.com/questions/72958304/meta-schema-features-in-vs-code-extension-warning-in-version-1-68-0
Open API専用拡張機能
https://github.com/arjun-g/vs-swagger-viewer
previewer
自分の環境だと、うまくうごかなかった
https://github.com/42Crunch/vscode-openapi
hoverしても解説がでないtakker.icon
Swagger Editorだと出るので、vscodeではなくこちらで書いたほうがやりやすそう
事例
ricapitolareはドメインのみにアクセスしたときswagger.jsonを返す
コード
/ci7lus-diary/2022.3.21#62387e56ae0f14000045f199
References
平静を保ち、コードを生成せよ 〜 OpenAPI Generator誕生の背景と軌跡 〜 / gunmaweb34 - Speaker Deck
contributerによる解説スライド
OpenAPI generatorを試してみる - Qiita
https://www.alpha.co.jp/blog/202208_02
https://qiita.com/KNR109/items/7e094dba6bcf37ed73cf
https://qiita.com/gcyata/items/342073fa7607fd4082bd
#2024-08-22 12:26:05
#2023-02-05 19:27:22
#2023-02-03 13:41:34
#2023-01-20 09:28:17
#2022-02-10 05:53:15